Skip Headers

Oracle® XML DB Developer's Guide 10g Release 2 (10.2) Part Number B14259-02 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# 20 Accessing Oracle XML DB Repository Data

This chapter describes how to access data in Oracle XML DB Repository using standard protocols such as FTP and HTTP(S)/WebDAV, and other Oracle XML DB resource Application Program Interfaces (APIs). It also introduces you to using `RESOURCE_VIEW` and `PATH_VIEW` as the SQL mechanism for accessing and manipulating repository data. It includes a table for comparing repository operations through the various resource APIs.

This chapter contains these topics:

- Overview of Oracle XML DB Foldering

- Repository Terminology and Supplied Resources

- Oracle XML DB Resources

- Accessing Oracle XML DB Repository Resources

- Navigational or Path Access

- Query-Based Access

- Accessing Repository Data Using Servlets

- Accessing Data Stored in Repository Resources

- Managing and Controlling Access to Resources

## Overview of Oracle XML DB Foldering

Using the foldering feature in Oracle XML DB you can store content in the database in hierarchical structures, as opposed to traditional relational database structures.

Figure 20-1 is an example of a hierarchical structure that shows a typical tree of folders and files in Oracle XML DB Repository. The top of the tree shows '/', the root folder.

Foldering allows applications to access hierarchically indexed content in the database using the FTP, HTTP(S), and WebDAV protocol standards as if the database content were stored in a file system.

This chapter provides an overview of how to access data in Oracle XML DB Repository folders using the standard protocols. It discusses APIs that you can use to access the repository object hierarchy using Java, SQL, and PL/SQL.

Figure 20-1 A Folder Tree, Showing Hierarchical Structures in the Repository

Description of "Figure 20-1 A Folder Tree, Showing Hierarchical Structures in the Repository"

Note: Folder `/sys` is used by Oracle XML DB to maintain system-defined XML schemas, Access Control Lists (ACLs), and so on. Do not add or modify any data in folder `/sys`.

See Also: Chapter 22, "SQL Access Using RESOURCE_VIEW and PATH_VIEW" Chapter 23, "PL/SQL Access Using DBMS_XDB" Chapter 22, "Java Access to Repository Data Using Resource API for Java" Chapter 25, "FTP, HTTP(S), and WebDAV Access to Repository Data"

## Repository Terminology and Supplied Resources

Oracle XML DB Repository is the set of database objects, across all XML and database schemas, that are mapped to path names. It is a connected, directed, acyclic graph of resources, with a single root node (`/`). Each resource in the graph has one or more associated path names: the repository supports multiple links to a given resource. The repository can be thought of as a file system of objects rather than files.

### Repository Terminology

The following list describes terms used in Oracle XML DB Repository:

- resource – Any object or node in the repository hierarchy. Resources are identified by URLs.

  See Also: "Overview of Oracle XML DB Repository" "Oracle XML DB Resources"

- folder – A resource that can contain other resources. Sometimes called a directory.

- path name – A hierarchical name representing a path to a resource. It is composed of a slash (`/`) representing the root, possibly followed by path elements separated by slashes. A path element is the name of a repository resource. A path element may be composed of any character in the database character set except `\` and `/`, which have special meaning in Oracle XML DB. The slash (`/`) is the default name separator in a path name. The backslash (`\`) is used to escape special characters, giving them a literal interpretation. The Oracle XML DB configuration file, `xdbconfig.xml`, contains a list of user-defined characters that must not appear within a path name (`<invalid-pathname-chars>`).

- resource name or link name – The name of a resource within its parent folder. Resource names must be unique within a folder and are case-sensitive. Resource names are always in the UTF-8 character set (`NVARCHAR`).

- resource content – The body, or data, of a resource. This is what you get when you treat the resource as a file and ask for its content. This is always of type `XMLType`.

- `XDBBinary` element – An XML element that contains binary data. It is defined by the Oracle XML DB XML schema. `XDBBinary` elements are stored in the repository whenever unstructured binary data is uploaded into Oracle XML DB.

- access control list (ACL) – A list of database users that allowed access to one or more specific resources.

  See Also: Chapter 24, "Repository Resource Security"

Many terms used by Oracle XML DB have common synonyms used in other contexts, as shown in Table 20-1.

Table 20-1 Synonyms for Oracle XML DB Foldering Terms

Synonym | Foldering Term | Usage
--- | --- | ---
collection | folder | WebDAV
directory | folder | operating systems
privilege | privilege | permission
right | privilege | various
WebDAV folder | folder | web folder
role | group | access control
revision | version | RCS, CVS
file system | repository | operating systems
hierarchy | repository | various
file | resource | operating systems
binding | link | WebDAV

### Supplied Files and Folders

The list of supplied Oracle XML DB Repository files and folders is as follows. In addition to using these, you can create your own folders and files wherever you want.

    /public
    /sys
    /sys/acls
    /sys/acls/all_all_acl.xml
    /sys/acls/all_owner_acl.xml
    /sys/acls/bootstrap_acl.xml
    /sys/acls/ro_all_acl.xml
    /sys/apps
    /sys/asm
    /sys/log
    /sys/schemas
    /sys/schemas/PUBLIC
    /sys/schemas/PUBLIC/www.w3.org
    /sys/schemas/PUBLIC/www.w3.org/2001
    /sys/schemas/PUBLIC/www.w3.org/2001/xml.xsd
    /sys/schemas/PUBLIC/xmlns.oracle.com
    /sys/schemas/PUBLIC/xmlns.oracle.com/xdb
    /sys/schemas/PUBLIC/xmlns.oracle.com/xdb/XDBFolderListing.xsd
    /sys/schemas/PUBLIC/xmlns.oracle.com/xdb/XDBResource.xsd
    /sys/schemas/PUBLIC/xmlns.oracle.com/xdb/XDBSchema.xsd
    /sys/schemas/PUBLIC/xmlns.oracle.com/xdb/XDBStandard.xsd
    /sys/schemas/PUBLIC/xmlns.oracle.com/xdb/acl.xsd
    /sys/schemas/PUBLIC/xmlns.oracle.com/xdb/dav.xsd
    /sys/schemas/PUBLIC/xmlns.oracle.com/xdb/log
    /sys/schemas/PUBLIC/xmlns.oracle.com/xdb/log/ftplog.xsd
    /sys/schemas/PUBLIC/xmlns.oracle.com/xdb/log/httplog.xsd
    /sys/schemas/PUBLIC/xmlns.oracle.com/xdb/log/xdblog.xsd
    /sys/schemas/PUBLIC/xmlns.oracle.com/xdb/stats.xsd
    /sys/schemas/PUBLIC/xmlns.oracle.com/xdb/xdbconfig.xsd
    /xdbconfig.xml

## Oracle XML DB Resources

Oracle XML DB Repository resources conform to the Oracle XML DB XML schema `xdbresource.xsd`. The elements in a resource include those needed to persistently store WebDAV-defined properties, such as creation date, modification date, WebDAV locks, owner, ACL, language, and character set.

Contents Element in Resource Index

A resource index has a special element called `Contents` that contains the contents of the resource.

any Element

The XML schema for a resource also defines an `any` element, with `maxoccurs` attribute unbounded. An `any` element can contain any element outside of the Oracle XML DB XML namespace. Arbitrary instance-defined properties can be associated with the resource.

### Where Is Repository Data Stored?

Oracle XML DB stores Oracle XML DB Repository data in a set of tables and indexes to which you have access. If you register an XML schema and request that the tables be generated by Oracle XML DB, then the tables are created in your database schema. You are then able to see or modify them. Other users will not be able to see your tables unless you grant them permission to do so.

#### Names of Generated Tables

The names of the generated tables are assigned by Oracle XML DB and can be obtained by finding the `xdb:defaultTable` attribute in your XML schema document (or in the default XML schema document). When you register an XML schema, you can alternatively provide your own table name, instead of using the default name supplied by Oracle XML DB.

See Also: "Creating Default Tables During XML Schema Registration"

#### Defining Structured Storage for Resources

Applications that need to define structured storage for resources can do so by either:

- Subclassing the Oracle XML DB resource type. Subclassing Oracle XML DB resources requires privileges on the table `XDB$RESOURCE`.

- Storing data that conforms to a visible, registered XML schema.

  See Also: Chapter 5, "XML Schema Storage and Query: Basic"

#### ASM Virtual Folder

The ASM virtual folder, `/sys/asm`, is an exception to the description of the previous sections – its contents are ASM files and folders that are managed automatically by Oracle Automatic Storage Management (ASM).

See Also: "Accessing ASM Files Using Protocols and Resource APIs – For DBAs" Oracle Database Administrator's Guide

### Path-Name Resolution

The data relating a folder to its contents is managed by the Oracle XML DB hierarchical index. This provides a fast mechanism for evaluating path names, similar to the directory mechanisms used by operating-system file systems.

Resources that are folders have the `Container` attribute set to `TRUE`.

To resolve a resource name in a folder, the current user must have the following privileges:

- `resolve` privilege on the folder

- `read-properties` on the resource in that folder

If the user does not have these privileges, then the user receives an `access denied` error. Folder listings and other queries will not return a row when the `read-properties` privilege is denied on its resource.

Caution: Error handling in path-name resolution differentiates between invalid resource names and resources that are not folders, for compatibility with file systems. Because Oracle XML DB resources are accessible from outside Oracle XML DB Repository (using SQL), denying read access on a folder that contains a resource does not prevent read access to that resource.

### Resource Deletion

Deletion of a link deletes the resource pointed to by the link if and only if that was the last link to the resource and the resource is not versioned.

See Also: "Deleting Repository Resources: Examples"

## Accessing Oracle XML DB Repository Resources

There are two ways to access Oracle XML DB Repository resources:

- Navigational or path-based access. This is achieved using a hierarchical index of objects or resources. Each resource has one or more unique path names that reflect its location in the hierarchy. You can use navigational access to reference any `XMLType` object in the database, without regard to its location in the relational tablespace. See "Navigational or Path Access".

- SQL access to the repository. This is done using special views that expose resource properties and path names, and map hierarchical access operators onto the Oracle XML DB schema. See "Query-Based Access".

Figure 20-2 illustrates these two Oracle XML DB data access options.

See Also: "Oracle XML DB Application Design: A. How Structured Is Your Data?" for guidance on selecting an access method Table 20-3, "Accessing Oracle XML DB Repository: API Options" for a summary comparison of the access methods

Figure 20-2 Repository Data Access Options

Description of "Figure 20-2 Repository Data Access Options"

A Uniform Resource Locator (URL) is used to access an Oracle XML DB resource. A URL includes the host name, protocol information, path name, and resource name of the object.

## Navigational or Path Access

Oracle XML DB folders support the same protocol standards used by many operating systems. This allows an Oracle XML DB folder to function just like a native folder or directory in supported operating-system environments. For example, you can:

- Use Windows Explorer to open and access Oracle XML DB folders and resources the same way you access other directories or resources in the Windows NT file system, as shown in Figure 20-3.

- Access Oracle XML DB Repository data using HTTP(S)/WebDAV from an Internet Explorer browser, such as when viewing Web Folders, as shown in Figure 20-4.

Figure 20-3 Oracle XML DB Folders in Windows Explorer

Description of "Figure 20-3 Oracle XML DB Folders in Windows Explorer"

Figure 20-4 Accessing Repository Data Using HTTP(S)/WebDAV and Navigational Access From IE Browser: Viewing Web Folders

Description of "Figure 20-4 Accessing Repository Data Using HTTP(S)/WebDAV and Navigational Access From IE Browser: Viewing Web Folders"

### Accessing Oracle XML DB Resources Using Internet Protocols

Oracle Net Services provides one way of accessing database resources. Oracle XML DB support for Internet protocols provides another way of accessing database resources.

#### Where You Can Use Oracle XML DB Protocol Access

Oracle Net Services is optimized for record-oriented data. Internet protocols are designed for stream-oriented data, such as binary files or XML text documents. Oracle XML DB protocol access is a valuable alternative to Net Services in the following scenarios:

- Direct database access from file-oriented applications using the database like a file system

- Heterogeneous application server environments that require a uniform data access method (such as XML over HTTP, which is supported by most data servers, including MS SQL Server, Exchange, Notes, many XML databases, stock quote services and news feeds)

- Application server environments that require data in the form of XML text

- Web applications that use client-side XSL to format datagrams that do not need much application processing

- Web applications that use Java servlets that run inside the database

- Web access to XML-oriented stored procedures

#### Using Protocol Access

Follow these steps to use Oracle XML DB protocol access:

1. A connection object is established, and the protocol might read part of the request.

2. The protocol decides whether the user is already authenticated and wants to reuse an existing session or the connection must be re-authenticated (the latter is more common).

3. An existing session is pulled from the session pool, or else a new one is created.

4. If authentication has not been provided, and the request is HTTP `get` or `head`, then the session is run as the `ANONYMOUS` user. If the session has already been authenticated as the `ANONYMOUS` user, then there is no cost to reuse the existing session. If authentication has been provided, then the database re-authentication routines are used to authenticate the connection.

5. The request is parsed.

6. (HTTP only) If the requested path name maps to a servlet, then the servlet is invoked using Java Virtual Machine (VM). The servlet code writes the response to a response stream or asks `XMLType` instances to do so.

#### Retrieving Oracle XML DB Resources

When the protocol indicates that a resource is to be retrieved, the path name to the resource is resolved. Resources being fetched are always streamed out as XML, with the exception of resources containing the `XDBBinary` element, an element defined to be the XML binary data type, which have their contents streamed out in RAW form.

#### Storing Oracle XML DB Resources

When the protocol indicates that a resource must be stored, Oracle XML DB checks the document file name extension for `.xml`, `.xsl`, `.xsd`, and so on. If the document is XML, then a pre-parse step is done, whereby enough of the resource is read to determine the XML `schemaLocation` and `namespace` of the root element in the document. If a registered schema is located at the `schemaLocation` URL, and it has a definition for the root element of the current document, then the default table specified for that root element is used to store the contents of the resource.

#### Using Internet Protocols and XMLType: XMLType Direct Stream Write

Oracle XML DB supports Internet protocols at the `XMLType` level by using the `writeToStream()` Java method on `XMLType`. This method is natively implemented, and writes `XMLType` data directly to the protocol request stream. This avoids Java VM execution costs and the overhead of converting database data through Java datatypes and creating Java objects, resulting in significantly higher performance. Performance is further enhanced if the Java code deals only with XML element trees that are close to the root, and does not traverse too many of the leaf elements, so that relatively few Java objects are created.

See Also: Chapter 25, "FTP, HTTP(S), and WebDAV Access to Repository Data"

### Accessing ASM Files Using Protocols and Resource APIs – For DBAs

Automatic Storage Management (ASM) organizes database files into disk groups for simplified management and added benefits such as database mirroring and I/O balancing.

Repository access using protocols and resource APIs (such as `DBMS_XDB`) extends to Automatic Storage Management (ASM) files. ASM files are accessed in the virtual repository folder `/sys/asm`. However, this access is reserved for DBAs; it is not intended for developers.

A typical use of such access is to copy ASM files from one database instance to another. For example, a DBA can view folder `/sys/asm` in a graphical user interface using the WebDAV protocol, and then drag-and-drop a copy of a data-pump dumpset from an ASM disk group to an operating-system file system.

Virtual folder `/sys/asm` is created by default during Oracle XML DB installation. If the database is not configured to use ASM, the folder is empty and no operations are permitted on it.

Folder `/sys/asm` contains folders and subfolders that follow the hierarchy defined by the structure of an ASM fully qualified filename:

- It contains a subfolder for each mounted disk group.

- A disk-group folder contains a subfolder for each database that uses that disk group. In addition, a disk-group folder may contain files and folders corresponding to ASM aliases created by the administrator.

- A database folder contains file-type folders.

- A file-type folder contains ASM files, which are binary.

This hierarchy is shown in Figure 20-5, which omits directories created for aliases, for simplicity.

Figure 20-5 ASM Virtual Folder Hierarchy

Description of "Figure 20-5 ASM Virtual Folder Hierarchy"

The following usage restrictions apply to virtual folder `/sys/asm`. You cannot:

- query `/sys/asm` using SQL

- put regular files under `/sys/asm` (you can only only put ASM files there)

- move (rename) an ASM file to a different ASM disk group or to a folder outside ASM

- create hard links to existing ASM files or directories

In addition:

- You must have DBA privileges to view folder `/sys/asm`.

- To access `/sys/asm` using Oracle XML DB protocols, you must log in as a user other than `SYS`.

Again, ASM virtual-folder operations are intended only for DBAs, not developers.

See Also: "Using FTP with ASM Files" for an example of using protocol FTP with `/sys/asm` Oracle Database Administrator's Guide for information on the syntax of a fully qualified ASM filename and details on the virtual folder structure

## Query-Based Access

There are two views that enable SQL access to Oracle XML DB Repository data:

- `PATH_VIEW`

- `RESOURCE_VIEW`

Table 20-2 summarizes the differences between `PATH_VIEW` and `RESOURCE_VIEW`.

Table 20-2 Differences Between PATH_VIEW and RESOURCE_VIEW

PATH_VIEW | RESOURCE_VIEW
--- | ---
Contains link properties | No link properties
Has one row for each unique path in repository | Has one row for each resource in repository

Rows in these two repository views are of `XMLType`. In the `RESOURCE_VIEW`, the single path associated with a resource is arbitrarily chosen from among the possible paths that refer to the resource. Oracle XML DB provides SQL functions like `under_path` that enable applications to search for the resources contained (recursively) within a particular folder, obtain the resource depth, and so on.

DML can be used on the repository views to insert, rename, delete, and update resource properties and contents. Programmatic APIs must be used for other operations, such as creating links to existing resources.

See Also: Chapter 22, "SQL Access Using RESOURCE_VIEW and PATH_VIEW" for details on SQL access to Oracle XML DB Repository Chapter 24, "Repository Resource Security"

## Accessing Repository Data Using Servlets

Oracle XML DB implements Java Servlet API, version 2.2, with the following exceptions:

- All servlets must be distributable. They must expect to run in different VMs.

- WAR and `web.xml` files are not supported. Oracle XML DB supports a subset of the XML configurations in this file. An XSL style sheet can be applied to the `web.xml` to generate servlet definitions. An external tool must be used to create database roles for those defined in the `web.xml` file.

- JSP (Java Server Pages) support can be installed as a servlet and configured manually.

- `HTTPSession` and related classes are not supported.

- Only one servlet context (that is, one Web application) is supported.

  See Also: Chapter 27, "Writing Oracle XML DB Applications in Java"

## Accessing Data Stored in Repository Resources

The three main ways you can access data stored in Oracle XML DB Repository resources are through:

- Oracle XML DB resource APIs for Java

- A combination of Oracle XML DB resource views API and Oracle XML DB resource API for PL/SQL

- Internet protocols (HTTP(S)/WebDAV and FTP) and Oracle XML DB protocol server

Table 20-3 lists common Oracle XML DB Repository operations and describes how these operations can be accomplished using each of the three methods. The table shows functionality common to three methods. Note that not all the methods are equally suited to a particular set of tasks.

See Also: Chapter 22, "SQL Access Using RESOURCE_VIEW and PATH_VIEW" Chapter 23, "PL/SQL Access Using DBMS_XDB" Chapter 22, "Java Access to Repository Data Using Resource API for Java" Chapter 25, "FTP, HTTP(S), and WebDAV Access to Repository Data" Oracle Database PL/SQL Packages and Types Reference

Table 20-3 Accessing Oracle XML DB Repository: API Options

Data Access | SQL and PL/SQL | Protocols
--- | --- | ---
Create resource |
    DBMS_XDB.createResource()
    INSERT INTO PATH_VIEW VALUES (path, res, linkprop);
| HTTP: `PUT;` FTP: `PUT`
Update resource contents |
    UPDATE RESOURCE_VIEW SET resource =
      updateXML(res, '/Resource/Contents', lob)
      WHERE equals_path(res, path) > 0
| HTTP: `PUT;` FTP: `PUT`
Update resource properties |
    UPDATE RESOURCE_VIEW SET resource =
      updateXML(res, '/Resource/propname1',
                newval, '/Resource/propname2' ...)
      WHERE equals_path(res, path) > 0
| WebDAV: `PROPPATCH;`
Update resource ACL |
    UPDATE RESOURCE_VIEW SET resource =
      updateXML(res, '/ Resource/ACL', XMLType)
      WHERE equals_path(res, path) > 0
| —
Unlink resource (delete if last link) |
    DBMS_XDB.deleteResource()
    DELETE FROM RESOURCE_VIEW
      WHERE equals_path(res, path) > 0
| HTTP: `DELETE;` FTP:`delete`
Forcibly remove all links to resource |
    DBMS_XDB.deleteResource()
    DELETE FROM PATH_VIEW
      WHERE extractValue(res, 'display_name')
            = 'My resource'
| FTP: `quote rm_rf` `resource`
Move resource |
    UPDATE PATH_VIEW SET path = newpath
      WHERE equals_path(res, path) > 0
| WebDAV: `MOVE;` FTP: `rename`
Copy resource |
    INSERT INTO PATH_VIEW
      SELECT newpath, res, link FROM PATH_VIEW
        WHERE equals_path(res, oldpath) > 0
| WebDAV: `COPY;`
Create link to existing resource |
    CALL DBMS_XDB.link(srcpath IN VARCHAR2,
                       linkfolder IN VARCHAR2,
                       linkname IN VARCHAR2);
| —
Get binary or text representation of resource contents |
    SELECT XDBURIType(path).getBlob() FROM DUAL;

    SELECT p.res.extract('/Resource/Contents')
      FROM RESOURCE_VIEW p
      WHERE equals_path(res, path) > 0
| HTTP: `GET;` FTP: `get`
Get `XMLType` representation of resource contents |
    SELECT XDBURIType(path).getBlob().getXML FROM DUAL;

    SELECT extract(res, '/Resource/Contents/*')
      FROM RESOURCE_VIEW p
      WHERE equals_path(Res, path) > 0
| —
Get resource properties |
    SELECT extractValue(res, '/Resource/XXX')
      FROM RESOURCE_VIEW
      WHERE equals_path(res, path) > 0
| WebDAV: `PROPFIND (depth = 0);`
List directory |
    SELECT PATH FROM PATH_VIEW
      WHERE under_path(res, path, 1) > 0
| WebDAV: `PROPFIND (depth = 0);`
Create folder |
    Call DBMS_XDB.createFolder(VARCHAR2)
| WebDAV: `MKCOL;` FTP: `mkdir`
Unlink folder |
    DBMS_XDB.deleteResource()
    DELETE FROM PATH_VIEW
      WHERE equals_path(res, path) > 0;
| HTTP: `DELETE;` FTP: `rmdir`
Forcibly delete folder and all links to it |
    Call DBMS_XDB.deleteResource(VARCHAR2);
| —
Get resource with a row lock |
    SELECT ... FROM RESOURCE_VIEW FOR UPDATE ...;
| —
Add WebDAV lock on resource |
    DBMS_XDB.LockResource(path, true, true);
| WebDAV: `LOCK;` FTP: `quote lock`
Remove WebDAV lock |
    BEGIN
      DBMS_XDB.GetLockToken(path, deltoken);
      DBMS_XDB.UnlockToken(path, deltoken);
    END;
| WebDAV: `UNLOCK;` FTP: `quote unlock`
Commit changes |
    COMMIT;
| Automatic commit after each request
Rollback changes |
    ROLLBACK;
| —

## Managing and Controlling Access to Resources

You can set access control privileges on Oracle XML DB folders and resources.

See Also: Chapter 24, "Repository Resource Security" for more detail on using access control on Oracle XML DB folders Oracle Database PL/SQL Packages and Types Reference